/*
 * Project it.battlehorse.rcp.sl
 * Created on Apr 9, 2006
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * A copy of the LGPL is available also at
 * http://www.gnu.org/copyleft/lesser.html
 * 
 */ 
package it.battlehorse.rcp.sl;

/**
 * A service factory is a component which is able to serve instances of specific class types, which
 * represent the services which can be injected into serviceable objects. Service factories are
 * configured and registered with the {@code it.battlehorse.rcp.sl.service} extension point.
 * <p>
 * The {@link ServiceLocator} first invokes the {@code getServiceInstance()} method which
 * accepts the serviceable object as parameter. If a null value is returned, then the ServiceLocator tries with 
 * the no-argument {@code getServiceInstance()} method.  
 * <p>
 * Service factories may perform caching. A caching service factory always returns  the same instance
 * of the service. A non-caching service factory returns a new instance of the service for every 
 * invocation of {@code getServiceInstance() }.
 * <p>
 * Implementations should provide a no-argument constructor
 * 
 * @author Riccardo "battlehorse" Govoni [battlehorse@gmail.com]
 * @since Apr 9, 2006
 */
public interface IServiceFactory {
	
	/**
	 * Returns an instance of the service which is handled by this factory. Implementations may return 
	 * {@code null} if they need the serviceable object for proper construction of the
	 * service instances.
	 * 
	 * @return an instance of the service which is handled by this factory
	 * @throws ServiceException if something goes wrong while instantiating the service
	 */
	public Object getServiceInstance() throws ServiceException;
	
	/**
	 * Returns an instance of the service which is handled by this factory. The object which is currently
	 * requesting the service is passed as parameter, and the factory may use it to extract informations which
	 * it can use to create the service intance. 
	 * 
	 * @param serviceable the object which is currently requesting the service. 
	 * @return an instance of the service which is handled by this factory
	 * @throws ServiceException if something goes wrong while instantiating the service
	 */
	public Object getServiceInstance(Object serviceable) throws ServiceException;
	
	/**
	 * Returns whether the factory is a caching one or not
	 * 
	 * @return whether the factory is a caching one or not
	 */
	public boolean isCaching();
	
	/**
	 * Requires a change in the caching strategy. This method suggests a hint  which can be ignored
	 * by the factory 
	 * 
	 * @param cacheSetting the new caching strategy to be used
	 * @return {@code true} if the factory has performed the requested change, {@code false} if the 
	 * factory ignored the hint
	 */
	public boolean setCaching(boolean cacheSetting);

}
